<!DOCTYPE html>
<html>
  <head>
    <meta charset='utf-8'>
    <meta content='width=device-width, initial-scale=1.0' name='viewport'>
    <meta content='' name='description'>
    <meta content='Nils Nordman' name='author'>
    <link href='/images/howl.png' rel='shortcut icon'>
    <title>Howl :: howl.command</title>
    <link href="/stylesheets/bootstrap.min.css" media="screen" rel="stylesheet" type="text/css" />
    <link href="/stylesheets/syntax.css" media="screen" rel="stylesheet" type="text/css" />
    <link href="/stylesheets/howl.css" media="screen" rel="stylesheet" type="text/css" />
    <script src="https://code.jquery.com/jquery-1.12.3.min.js" type="text/javascript"></script>
    <script src="/javascripts/bootstrap.min.js" type="text/javascript"></script>
    
    <link href='//fonts.googleapis.com/css?family=Josefin+Slab' rel='stylesheet' type='text/css'>
    <link href='//fonts.googleapis.com/css?family=Open+Sans+Condensed:700' rel='stylesheet' type='text/css'>
  </head>
  <body class='doc doc_api doc_api_command'>
    <div class='container'>
      <div class='masthead'>
        <ul class='nav nav-pills'>
          <li>
            <a href='/'>
              <span class='glyphicon glyphicon-home'></span>
              Home
            </a>
          </li>
          <li>
            <a href='/doc/'>
              <span class='glyphicon glyphicon-book'></span>
              Documentation
            </a>
          </li>
          <li>
            <a href='/blog/'>
              <span class='glyphicon glyphicon-bullhorn'></span>
              Blog
            </a>
          </li>
          <li>
            <a href='/contact.html'>
              <span class='glyphicon glyphicon-inbox'></span>
              Contact
            </a>
          </li>
        </ul>
      </div>
      <ol class="breadcrumb"><li><a href="/">Home</a></li><li><a href='../'>Howl 0.4 Documentation</a></li><li>Api</li><li>howl.command</li></ol>
      <h1 id="howl.command">howl.command</h1>    <div class="toc">
      <div class="toc-title">
        <span>howl.command</span>
      </div>
      <div class="toc-entries">
<div class="toc-group">
<a href="#overview" class="toc-group-header overview">Overview</a>
</div>
<div class="toc-group">
<a href="#functions" class="toc-group-header functions">Functions</a>
<li class=""><a href="#alias">alias </a></li>
<li class=""><a href="#get">get </a></li>
<li class=""><a href="#names">names </a></li>
<li class=""><a href="#register">register </a></li>
<li class=""><a href="#run">run </a></li>
<li class=""><a href="#unregister">unregister </a></li>
</div>
<div class="toc-group">
<a href="#direct-command-call" class="toc-group-header direct_command_call">Direct command call</a>
</div>
</div>
</div>
&#x000A;&#x000A;<h2 id="overview">Overview</h2>&#x000A;&#x000A;<p>The howl.command module acts as the central registry of commands in Howl, and&#x000A;lets you register new commands, get information about currently available&#x000A;commands and execute commands directly.</p>&#x000A;&#x000A;<p>A command is a named piece of functionality initiated by the user, such as the&#x000A;<code>open</code> command that opens a file, or the <code>save</code> command that saves the current&#x000A;buffer. The user can invoke commands either explicitly by opening the command&#x000A;line and typing the name of the command, or indirectly via pressing a key&#x000A;<a href="bindings.html">binding</a>. The command module keeps track of all available&#x000A;commands in Howl and uses <a href="interact.html">interactions</a> to read user input as necessary.</p>&#x000A;&#x000A;<p>From an implementation perspective, a command definition is a simple table that&#x000A;provides the name of the command, a description, an optional <code>input</code> function&#x000A;and a <code>handler</code> function. As an example, consider a possible definition of an&#x000A;<code>open</code> command:</p>&#x000A;<pre class="highlight moonscript"><span class="n">howl</span><span class="p">.</span><span class="n">command</span><span class="p">.</span><span class="n">register</span><span class="w">&#x000A;  </span><span class="ss">name:</span><span class="w"> </span><span class="s1">'open'</span><span class="p">,</span><span class="w">&#x000A;  </span><span class="ss">description:</span><span class="w"> </span><span class="s1">'Open a file'</span><span class="w">&#x000A;  </span><span class="ss">input:</span><span class="w"> </span><span class="n">howl</span><span class="p">.</span><span class="n">interact</span><span class="p">.</span><span class="n">select_file</span><span class="w">&#x000A;  </span><span class="ss">handler:</span><span class="w"> </span><span class="p">(</span><span class="n">file</span><span class="p">)</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="n">howl</span><span class="p">.</span><span class="n">app</span><span class="o">\</span><span class="n">open_file</span><span class="w"> </span><span class="n">file</span><span class="w">&#x000A;</span></pre>&#x000A;<p>When the user invokes this command, the <code>input</code> function is called first. In&#x000A;this case an <a href="interact.html">interaction</a> called <code>select_file</code> is used as the input function.&#x000A;It displays the command line and a completion list, allowing the user to&#x000A;navigate the file system and select a file. The <code>select_file</code> function returns a&#x000A;<a href="io/file.html">File</a> object for the selected file. The <code>handler</code> function is then called and&#x000A;passed the <a href="io/file.html">File</a> object as an argument. This invokes the <code>open_file</code> function&#x000A;to open the file.</p>&#x000A;&#x000A;<p>If an <code>input</code> function returns <code>nil</code>, or raises an error, the <code>handler</code> is not&#x000A;called. The <code>input</code> field is optional and commands that provide it are called&#x000A;<em>interactive</em> commands. If a command does not specify an <code>input</code>, the <code>handler</code>&#x000A;function is called directly with no arguments.</p>&#x000A;&#x000A;<p>While any function can serve as the <code>input</code>, inputs often use <a href="interact.html">interactions</a>.&#x000A;Using interactions allows easy re-use of common user interaction patterns such&#x000A;as asking the user a yes/no question or getting the user to select a directory.</p>&#x000A;&#x000A;<p>Commands can be invoked via code by calling <code>howl.command.run</code> or calling the&#x000A;command name directly as a field of command module, for example&#x000A;<code>howl.command.save!</code>, which invokes the &ldquo;save&rdquo; command. Command names that&#x000A;contain special characters such as hyphens and spaces can be invoked by an&#x000A;<em>accessible</em> name, in which all special characters are replaced with&#x000A;underscores. For example, the &ldquo;buffer-reload&rdquo; command can be invoked via&#x000A;<code>howl.command.buffer_reload!</code></p>&#x000A;&#x000A;<hr>&#x000A;&#x000A;<p><em>See also</em>:</p>&#x000A;&#x000A;<ul>&#x000A;<li>The <a href="../spec/command_spec.html">spec</a> for howl.command</li>&#x000A;<li>The <a href="interact.html">interact</a> module for more information about interactions</li>&#x000A;</ul>&#x000A;&#x000A;<h2 id="functions">Functions</h2>&#x000A;&#x000A;<h3 id="alias">alias <span class="arg-list">(target, name, opts = {})</span></h3>&#x000A;&#x000A;<p>Creates an alias, <code>name</code> for an existing command, <code>target</code>. The command&#x000A;specified by <code>target</code> is required to exist when calling this function. <code>opts</code> is&#x000A;an optional table of options. Currently it can contain one field:</p>&#x000A;&#x000A;<ul>&#x000A;<li><code>deprecated</code>: If set to <code>true</code>, the alias is marked as deprecated. This will&#x000A;show in the command completion.</li>&#x000A;</ul>&#x000A;&#x000A;<h3 id="get">get <span class="arg-list">(name)</span></h3>&#x000A;&#x000A;<p>Retrieves the command definition for the command with name <code>name</code>, or <code>nil</code> if&#x000A;no such command is present.</p>&#x000A;&#x000A;<h3 id="names">names <span class="arg-list">()</span></h3>&#x000A;&#x000A;<p>Returns a list of names for the currently available commands.</p>&#x000A;&#x000A;<h3 id="register">register <span class="arg-list">(def)</span></h3>&#x000A;&#x000A;<p>Registers a new command. <code>def</code> is a table containing the following fields:</p>&#x000A;&#x000A;<ul>&#x000A;<li><code>name</code>: <em>[required]</em> The name of the command.</li>&#x000A;<li><code>description</code>: <em>[required]</em> A short description of the command.</li>&#x000A;<li><code>handler</code>: <em>[required]</em> A function that is invoked to execute the command. The&#x000A;handler receives arguments returned by the <code>input</code> field, if provided.</li>&#x000A;<li><code>input</code>: <em>[optional]</em> A function that is invoked to read user input. If&#x000A;present, this function is invoked before the handler, and all return values are&#x000A;passed to the handler as arguments.</li>&#x000A;</ul>&#x000A;&#x000A;<h3 id="run">run <span class="arg-list">(cmd_string = nil)</span></h3>&#x000A;&#x000A;<p>Parses and runs <code>cmd_string</code>, if given. If <code>cmd_string</code> is not provided, then&#x000A;the <a href="ui/command_line.html">command line</a> is displayed and the user is prompted for the command to run.&#x000A;If <code>cmd_string</code> refers to an interactive command, the <code>input</code> function is called&#x000A;first, and the results of the input function are passed to the <code>handler</code>&#x000A;function.</p>&#x000A;&#x000A;<p>Interactive commands can be invoked with a string containing the command name&#x000A;followed by a space and some additional text, which then gets handled by the&#x000A;command&rsquo;s <code>input</code> function. For example <code>command.run &quot;open path/to/folder&quot;</code>&#x000A;behaves the same as running <code>open</code> and then typing &ldquo;path/to/folder&rdquo;.</p>&#x000A;&#x000A;<p>Here are some examples of invoking commands using the <code>run</code> function:</p>&#x000A;<pre class="highlight moonscript"><span class="n">howl</span><span class="p">.</span><span class="n">command</span><span class="p">.</span><span class="n">run</span><span class="w"> </span><span class="s2">"save"</span><span class="w">  </span><span class="c1">-- invokes "save"</span><span class="w">&#x000A;&#x000A;</span><span class="n">howl</span><span class="p">.</span><span class="n">command</span><span class="p">.</span><span class="n">run</span><span class="w"> </span><span class="s2">"buffer-reload"</span><span class="w">  </span><span class="c1">-- invokes "buffer_reload"</span><span class="w">&#x000A;&#x000A;</span><span class="c1">-- The following invokes the "open" command. Since it is an interactive command,</span><span class="w">&#x000A;</span><span class="c1">-- this displays the command line and lets the user select a file to open.</span><span class="w">&#x000A;</span><span class="n">howl</span><span class="p">.</span><span class="n">command</span><span class="p">.</span><span class="n">run</span><span class="w"> </span><span class="s2">"open"</span><span class="w">&#x000A;</span></pre>&#x000A;<h3 id="unregister">unregister <span class="arg-list">(name)</span></h3>&#x000A;&#x000A;<p>Unregisters the command with name <code>name</code>, along with any aliases pointing to&#x000A;the command.</p>&#x000A;&#x000A;<h2 id="direct-command-call">Direct command call</h2>&#x000A;&#x000A;<p>Indexing the command module itself using any command name returns a function&#x000A;that can be used to invoke the command. When invoked this way, arguments may be&#x000A;provided to the function that are passed through directly to the handler. The&#x000A;<code>input</code> function is not run for interactive commands invoked this way.</p>&#x000A;&#x000A;<p>Commands that have special characters such as hyphens or spaces in their name&#x000A;can be indexed by using an <em>accessible</em> command name, in which all special&#x000A;characters of the original command name are replaced with underscores.</p>&#x000A;&#x000A;<p>Here are some examples of invoking commands via the direct call:</p>&#x000A;<pre class="highlight moonscript"><span class="n">howl</span><span class="p">.</span><span class="n">command</span><span class="p">.</span><span class="n">save</span><span class="o">!</span><span class="w">  </span><span class="c1">-- invoke "save"</span><span class="w">&#x000A;&#x000A;</span><span class="n">howl</span><span class="p">.</span><span class="n">command</span><span class="p">.</span><span class="n">buffer_reload</span><span class="o">!</span><span class="w">  </span><span class="c1">-- invokes "buffer-reload"</span><span class="w">&#x000A;&#x000A;</span><span class="c1">-- The following invokes the "open" command, but does not prompt the user for</span><span class="w">&#x000A;</span><span class="c1">-- a file to open. It just opens /path/to/myfile</span><span class="w">&#x000A;</span><span class="n">howl</span><span class="p">.</span><span class="n">command</span><span class="p">.</span><span class="n">open</span><span class="w"> </span><span class="n">howl</span><span class="p">.</span><span class="n">io</span><span class="p">.</span><span class="nc">File</span><span class="p">(</span><span class="s1">'/path/to/some_file'</span><span class="p">)</span><span class="w">&#x000A;</span></pre>
      <div class='footer text-muted'>
        <a href='/'>
          <img width="50" height="50" class="footer-logo" src="/images/howl.png" />
        </a>
        <div class='footer-follow'>
          <p>
            <a class='twitter-follow-button' data-lang='en' data-show-count='false' href='https://twitter.com/howleditor' rel='me'>
              Follow @howleditor
            </a>
          </p>
          <p>
            <a class='twitter-share-button' data-count='none' data-hashtags='howleditor' data-lang='en' data-text='The Howl Editor, a general purpose, light-weight customizable editor.' data-url='http://howl.io' href='https://twitter.com/share'>
              Tweet
            </a>
          </p>
        </div>
        <div class='footer-blurb'>
          <div>The Howl editor.</div>
          <div>
            Copyright 2012-2016
            <a class='alert-link' href='https://github.com/howl-editor/howl/contributors'>
              The Howl Developers.
            </a>
          </div>
        </div>
      </div>
    </div>
    <script>
      <!-- / GA -->
      (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
      })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
      ga('create', 'UA-45283282-1', 'howl.io');
      ga('send', 'pageview');
      <!-- / Twitter -->
      !function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];
      if(!d.getElementById(id)){js=d.createElement(s);js.id=id;
      js.src="//platform.twitter.com/widgets.js";
      fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");
    </script>
  </body>
</html>
